 /*******************************************************************************
  * Copyright (c) 2004, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.osgi.service.resolver;


 /**
  * A helper class that provides convenience methods for manipulating
  * state objects. <code>PlatformAdmin</code> provides an access point
  * for a state helper.
  * <p>
  * Clients should not implement this interface.
  * </p>
  * @since 3.1
  * @see PlatformAdmin#getStateHelper
  */
 public interface StateHelper {
     /**
      * Indicates that access is encouraged to an <code>ExportPackageDescription</code>.
      */
     public static int ACCESS_ENCOURAGED = 0x01;
     /**
      * Indicates that access is discouraged to an <code>ExportPackageDescription</code>.
      */
     public static int ACCESS_DISCOURAGED = 0x02;

     /**
      * An option to include packages available from the execution environment when
      * getting the visible packages of a bundle.
      * @see StateHelper#getVisiblePackages(BundleDescription, int)
      */
     public static int VISIBLE_INCLUDE_EE_PACKAGES = 0x01;

     /**
      * Returns all bundles in the state depending on the given bundles. The given bundles
      * appear in the returned array.
      *
      * @param bundles the initial set of bundles
      * @return an array containing bundle descriptions for the given roots and all
      * bundles in the state that depend on them
      */
     public BundleDescription[] getDependentBundles(BundleDescription[] bundles);

     /**
      * Returns all the prerequisite bundles in the state for the given bundles. The given
      * bundles appear in the returned array.
      * @param bundles the inital set of bundles
      * @return an array containing bundle descriptions for the given leaves and their
      * prerequisite bundles in the state.
      * @since 3.2
      */
     public BundleDescription[] getPrerequisites(BundleDescription[] bundles);

     /**
      * Returns all unsatisfied constraints in the given bundle. Returns an
      * empty array if no unsatisfied constraints can be found.
      * <p>
      * Note that a bundle may have no unsatisfied constraints and still not be
      * resolved.
      * </p>
      *
      * @param bundle the bundle to examine
      * @return an array containing all unsatisfied constraints for the given bundle
      */
     public VersionConstraint[] getUnsatisfiedConstraints(BundleDescription bundle);

     /**
      * Returns all unsatisfied constraints in the given bundles that have no possible supplier.
      * Returns an empty array if no unsatisfied leaf constraints can be found.
      * <p>
      * The returned constraints include only the unsatisfied constraints in the given
      * state that have no possible supplier (leaf constraints). There may
      * be additional unsatisfied constraints in the given bundles but these will have at
      * least one possible supplier. In this case the possible supplier of the constraint
      * is not resolved for some reason. For example, a given state only has Bundles X and Y
      * installed and Bundles X and Y have the following constraints:
      * </p>
      * <pre>
      * Bundle X requires Bundle Y
      * Bundle Y requires Bundle Z</pre>
      * <p>
      * In this case Bundle Y has an unsatisfied constraint leaf on Bundle Z. This will
      * cause Bundle X's constraint on Bundle Y to be unsatisfied as well because the
      * bundles are involved in a dependency chain. Bundle X's constraint on Bundle Y is
      * not considered a leaf because there is a possible supplier Y in the given state.
      * </p>
      * <p>
      * Note that a bundle may have no unsatisfied constraints and still not be
      * resolved.
      * </p>
      *
      * @param bundles the bundles to examine
      * @return an array containing all unsatisfied leaf constraints for the given bundles
      * @since 3.2
      */
     public VersionConstraint[] getUnsatisfiedLeaves(BundleDescription[] bundles);

     /**
      * Returns whether the given package specification constraint is resolvable.
      * A package specification constraint may be
      * resolvable but not resolved, which means that the bundle that provides
      * it has not been resolved for some other reason (e.g. another constraint
      * could not be resolved, another version has been picked, etc).
      *
      * @param specification the package specification constraint to be examined
      * @return <code>true</code> if the constraint can be resolved,
      * <code>false</code> otherwise
      */
     public boolean isResolvable(ImportPackageSpecification specification);

     /**
      * Returns whether the given bundle specification constraint is resolvable.
      * A bundle specification constraint may be
      * resolvable but not resolved, which means that the bundle that provides
      * it has not been resolved for some other reason (e.g. another constraint
      * could not be resolved, another version has been picked, etc).
      *
      * @param specification the bundle specification constraint to be examined
      * @return <code>true</code> if the constraint can be resolved,
      * <code>false</code> otherwise
      */
     public boolean isResolvable(BundleSpecification specification);

     /**
      * Returns whether the given host specification constraint is resolvable.
      * A host specification constraint may be
      * resolvable but not resolved, which means that the bundle that provides
      * it has not been resolved for some other reason (e.g. another constraint
      * could not be resolved, another version has been picked, etc).
      *
      * @param specification the host specification constraint to be examined
      * @return <code>true</code> if the constraint can be resolved,
      * <code>false</code> otherwise
      */
     public boolean isResolvable(HostSpecification specification);

     /**
      * Sorts the given array of <strong>resolved</strong> bundles in pre-requisite order. If A
      * requires B, A appears after B.
      * Fragments will appear after all of their hosts. Constraints contributed by fragments will
      * be treated as if contributed by theirs hosts, affecting their position. This is true even if
      * the fragment does not appear in the given bundle array.
      * <p>
      * Unresolved bundles are ignored.
      * </p>
      *
      * @param toSort an array of bundles to be sorted
      * @return any cycles found
      */
     public Object [][] sortBundles(BundleDescription[] toSort);

     /**
      * Returns a list of all packages that the specified bundle has access to which are
      * exported by other bundles. This takes into account all constraint specifications
      * from the specified bundle (Import-Package, Require-Bundle etc). A deep dependancy
      * search is done for all packages which are available through the required bundles and
      * any bundles which are reexported. This method also takes into account all directives
      * which may be specified on the constraint specifications (e.g. uses, x-friends etc.) <p>
      *
      * The returned list will not include any packages which are exported by the system bundle
      * on the behave of the running execution environment. For example, when running on a
      * 1.4.2 JRE the system bundle will export the javax.xml.parsers package. These types of
      * system packages will are not included in the returned list.
      * <p>
      * Same as calling getVisiblePackages(bundle, 0)
      * @param bundle a bundle to get the list of packages for.
      * @return a list of all packages that the specified bundle has access to which are
      * exported by other bundles.
      */
     public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle);

     /**
      * Returns a list of all packages that the specified bundle has access to which are
      * exported by other bundles. This takes into account all constraint specifications
      * from the specified bundle (Import-Package, Require-Bundle etc). A deep dependancy
      * search is done for all packages which are available through the required bundles and
      * any bundles which are reexported. This method also takes into account all directives
      * which may be specified on the constraint specifications (e.g. uses, x-friends etc.)
      * @param bundle a bundle to get the list of packages for.
      * @param options the options for selecting the visible packages
      * @return a list of all packages that the specified bundle has access to which are
      * exported by other bundles.
      * @see StateHelper#VISIBLE_INCLUDE_EE_PACKAGES
      * @since 3.3
      */
     public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle, int options);

     /**
      * Returns the access code that the specified <code>BundleDescription</code> has to the
      * specified <code>ExportPackageDescription</code>.
      * @param bundle the bundle to find the access code for
      * @param export the export to find the access code for
      * @return the access code to the export.
      * @see StateHelper#ACCESS_ENCOURAGED
      * @see StateHelper#ACCESS_DISCOURAGED
      */
     public int getAccessCode(BundleDescription bundle, ExportPackageDescription export);
 }

